---
overviewHeaders: [2, 3]
---

# lib.dts

- **Type:**

```ts
type Dts =
  | {
      bundle?: boolean | { bundledPackages?: string[] };
      distPath?: string;
      build?: boolean;
      abortOnError?: boolean;
      autoExtension?: boolean;
      alias?: Record<string, string>;
      tsgo?: boolean;
    }
  | boolean;
```

- **Default:** `undefined`
- **CLI:** `--dts` / `--no-dts`

Configure the generation of the TypeScript declaration files.

## Boolean type

Declaration files generation is an optional feature, you can set `dts: true` to enable [bundleless declaration files](/guide/advanced/dts#bundleless-declaration-files) generation.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      dts: true, // [!code highlight]
    },
  ],
};
```

If you want to disable declaration files generation, you can set `dts: false` or do not specify the `dts` option.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      dts: false, // [!code highlight]
    },
  ],
};
```

## Object type

If you want to customize the declaration files generation, you can set the `dts` option to an object.

### dts.bundle

- **Type:** `boolean | { bundledPackages?: string[] }`
- **Default:** `false`

Whether to bundle the declaration files.

If you want to [bundle declaration files](/guide/advanced/dts#bundle-declaration-files) files, you should:

1. Install [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor) as a development dependency, which is the underlying tool used for bundling declaration files.

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @microsoft/api-extractor -D" />

2. Set `dts.bundle` to `true`.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      // [!code highlight:3]
      dts: {
        bundle: true,
      },
    },
  ],
};
```

#### dts.bundle.bundledPackages

- **Type:** `string[]`

Specifies the dependencies whose declaration files should be bundled. This configuration is passed to the [bundledPackages](https://api-extractor.com/pages/configs/api-extractor_json/#bundledpackages) option of `@microsoft/api-extractor`.

By default, Rslib determines externalized dependencies based on the following configurations. For details, refer to [Handle third-party dependencies](/guide/advanced/third-party-deps).

- [autoExternal](/config/lib/auto-external) configuration
- [output.externals](/config/rsbuild/output#outputexternals) configuration

Direct dependencies (declared in `package.json`) that are not externalized will be automatically added to `bundledPackages`, and their declaration files will be bundled into the final output.

When the default behavior does not meet the requirements, you can explicitly specify the dependencies whose declaration files need to be bundled through `dts.bundle.bundledPackages`. After setting this configuration, the above default behavior will be completely overwritten.

This is typically used for bundling transitive dependencies (dependencies of direct dependencies). For example, if the project directly depends on `foo`, and `foo` depends on `bar`, you can bundle both `foo` and `bar`'s declaration files as follows:

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      dts: {
        // [!code highlight:3]
        bundle: {
          bundledPackages: ['foo', 'bar'],
        },
      },
    },
  ],
};
```

::: note
`bundledPackages` can be specified with the [minimatch](https://www.npmjs.com/package/minimatch) syntax, but will only match the declared direct dependencies in `package.json`.
:::

### dts.distPath

- **Type:** `string`

The output directory of declaration files.

#### Default value

The default value follows the priority below:

1. The `dts.distPath` value in the current lib configuration.
2. The `declarationDir` value in the `tsconfig.json` file.
3. The [output.distPath](/config/rsbuild/output#outputdistpath) or [output.distPath.root](/config/rsbuild/output#outputdistpath) value in the current lib configuration.

#### Example

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      // [!code highlight:3]
      dts: {
        distPath: './dist-types',
      },
    },
  ],
};
```

### dts.build

- **Type:** `boolean`
- **Default:** `false`

Whether to generate declaration files with building the project references. This is equivalent to using the `--build` flag with the `tsc` command. See [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) for more details.

When the project references are configured but the referenced project has not been built separately (for example, the source code of other projects is directly referenced in monorepo, but the corresponding declaration file is missing in the project), this option needs to be enabled to ensure that the declaration files of referenced projects can be generated correctly, thereby ensuring the integrity of the type system.

::: note

When this option is enabled, you must explicitly set `declarationDir` or `outDir` in `tsconfig.json` in order to meet the build requirements.

:::

### dts.abortOnError

- **Type:** `boolean`
- **Default:** `true`

Whether to abort the build process when an error occurs during declaration files generation.

By default, type errors will cause the build to fail.

When `abortOnError` is set to `false` like below, the build will still succeed even if there are type issues in the code.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      // [!code highlight:3]
      dts: {
        abortOnError: false,
      },
    },
  ],
};
```

::: warning

When this configuration is disabled, there is no guarantee that the type files will be generated correctly.

:::

### dts.autoExtension

- **Type:** `boolean`
- **Default:** `false`

Whether to automatically set the declaration file extension based on the [format](/config/lib/format) option.

#### Default extension

By default that when `dts.autoExtension` is `false`, the declaration file extension will be `.d.ts`.

When `dts.autoExtension` is set to `true`, the declaration file extension will be:

- `.d.ts` with `esm` format and `.d.cts` with `cjs` format when `type: module` in `package.json`.

- `.d.ts` with `cjs` format and `.d.mts` with `esm` format when `type: commonjs` or no `type` field in `package.json`.

::: note

1. It follows the same logic as [lib.autoExtension](/config/lib/auto-extension), but the default value is different since the declaration file extension may cause some issues with different module resolution strategies.

2. Type declaration import extensions are controlled by the [redirect.dts.extension](/config/lib/redirect#redirectdtsextension) configuration.

3. When [dts.tsgo](/config/lib/dts#dtstsgo) is enabled, if the project also enables [dts.build](/config/lib/dts#dtsbuild) or emits declaration files with different extensions to the same directory, `dts.autoExtension` may not work correctly.

:::

### dts.alias

- **Type:** `Record<string, string>`
- **Default:** `{}`

Configure the path alias for declaration files.

`dts.alias` will be merged with `compilerOptions.paths` configured in `tsconfig.json` and `dts.alias` has a higher priority.

In most cases, you don't need to use `dts.alias`, but consider using it when you need to use path alias only in declaration files without wanting to affect JavaScript outputs. For example, map the declaration file of `foo` to `./compiled/foo`.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      // [!code highlight:5]
      dts: {
        alias: {
          foo: './compiled/foo',
        },
      },
    },
  ],
};
```

### dts.tsgo

- **Type:** `boolean`
- **Default:** `false`

Whether to generate declaration files with [tsgo](https://github.com/microsoft/typescript-go), which can provide faster generation of declaration files, especially for large projects.

::: tip

This feature is currently an **experimental feature**. Since tsgo is still in the **experimental stage**, there may be some bugs and unresolved issues or limitations. So, make sure to fully test it in your project before enabling this option.

:::

To enable this option, you need to:

1. Install [@typescript/native-preview](https://www.npmjs.com/package/@typescript/native-preview) as a development dependency.

<PackageManagerTabs command="add @typescript/native-preview -D" />

::: tip Version requirements

`@typescript/native-preview` requires Node.js 20.6.0 or higher.

:::

2. Configure in the Rslib config file:

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      dts: {
        tsgo: true, // [!code highlight]
      },
    },
  ],
};
```

3. In order to ensure the consistency of local development, you need to install the corresponding [VS Code Preview Extension](https://marketplace.visualstudio.com/items?itemName=TypeScriptTeam.native-preview) and add the following configuration in the VS Code settings:

```json title=".vscode/settings.json"
{
  "typescript.experimental.useTsgo": true
}
```
